OpenClaw 定时任务配置完全指南

定时任务让 AI 助理从"被动响应"变为"主动服务"。通过 cron 工具，你可以配置每日报告、定期检查、定时提醒等自动化任务。本文详细介绍定时任务的配置方法和实战应用。

一、工具概述

cron 工具能力

调度执行：支持 cron 表达式、间隔执行、一次性执行
任务类型：agentTurn（AI 任务）、systemEvent（系统事件）
交付方式：announce（通知）、webhook（回调）
会话管理：main（主会话）、isolated（隔离会话）

基本用法

javascript

// 添加定时任务
cron(
  action="add",
  job={
    name: "任务名称",
    schedule: {
      kind: "cron",
      expr: "0 8 * * *",  // 每天 8:00
      tz: "Asia/Shanghai"
    },
    payload: {
      kind: "agentTurn",
      message: "执行任务内容",
      timeoutSeconds: 300
    },
    sessionTarget: "isolated"
  }
)

// 查看任务列表
cron(action="list")

// 立即执行任务
cron(action="run", jobId="任务 ID")

// 删除任务
cron(action="remove", jobId="任务 ID")

二、调度类型详解

1. Cron 表达式（周期性执行）

javascript

// 每天 8:00
{ kind: "cron", expr: "0 8 * * *", tz: "Asia/Shanghai" }

// 每周一 9:00
{ kind: "cron", expr: "0 9 * * 1", tz: "Asia/Shanghai" }

// 每小时整点
{ kind: "cron", expr: "0 * * * *" }

// 每 15 分钟
{ kind: "cron", expr: "*/15 * * * *" }

// 每天 8:00 和 20:00
{ kind: "cron", expr: "0 8,20 * * *" }

// 工作日 9:00
{ kind: "cron", expr: "0 9 * * 1-5", tz: "Asia/Shanghai" }

Cron 表达式格式

* * * * *
│ │ │ │ │
│ │ │ │ └─ 星期 (0-7, 0 和 7 都是周日)
│ │ │ └─── 月份 (1-12)
│ │ └───── 日期 (1-31)
│ └─────── 小时 (0-23)
└───────── 分钟 (0-59)

特殊字符

字符	含义	示例
*	任意值	`* * * * *` 每分钟
,	分隔多个值	`0 8,12,18 * * *` 8 点、12 点、18 点
-	范围	`0 9-17 * * 1-5` 工作日 9-17 点
/	间隔	`/15 * * *` 每 15 分钟

2. 间隔执行（相对时间）

javascript

// 每 30 分钟执行一次
{ kind: "every", everyMs: 1800000 }

// 每 24 小时执行一次
{ kind: "every", everyMs: 86400000 }

// 每 24 小时执行，从指定时间开始
{ 
  kind: "every", 
  everyMs: 86400000,
  anchorMs: new Date("2026-03-19T08:00:00+08:00").getTime()
}

3. 一次性执行（绝对时间）

javascript

// 在指定时间执行一次
{ 
  kind: "at", 
  at: "2026-03-20T08:00:00+08:00" 
}

// 10 分钟后执行
{ 
  kind: "at", 
  at: new Date(Date.now() + 10 * 60000).toISOString() 
}

三、实战案例 1：每日早晨报告

场景说明

每天早晨 8:00 自动执行：

检查未读邮件
查看今日日历
获取天气预报
生成汇总报告发送到飞书

完整配置

javascript

cron(
  action="add",
  job={
    name: "每日早晨报告",
    schedule: {
      kind: "cron",
      expr: "0 8 * * *",
      tz: "Asia/Shanghai"
    },
    payload: {
      kind: "agentTurn",
      message: `
请生成每日早晨报告，包括：

1. 检查未读邮件（如有紧急邮件请标注）
   - 使用 message 工具查询邮件

2. 查看今日日历事件（特别是 2 小时内的）
   - 列出所有事件的时间和主题

3. 获取驻马店天气预报
   - 使用 web_search 或 exec 调用天气 API

4. 检查是否有待处理的提醒
   - 查看记忆文件中的提醒

生成简洁的报告，使用以下格式：

📧 邮件：[数量] 封未读，[紧急内容摘要]
📅 今日日程：[事件列表]
🌤️ 天气：[温度、天气状况、建议]
⏰ 提醒：[待办事项]

如果没有重要内容，回复"一切正常"即可。
      `,
      timeoutSeconds: 300
    },
    sessionTarget: "isolated",
    delivery: {
      mode: "announce"
    }
  }
)

执行结果示例

📊 每日早晨报告 - 2026 年 3 月 19 日

📧 邮件：3 封未读
   - [紧急] 项目评审会议改期通知（今天 10:00）
   - 系统自动备份完成报告
   - 订阅周刊：AI 技术前沿第 52 期

📅 今日日程：
   - 10:00 项目评审会议（已改期）
   - 14:00 团队周会
   - 16:30 客户演示

🌤️ 天气：驻马店 晴 12-23°C
   建议：天气晴朗，适合户外活动

⏰ 提醒：
   - 明天是母亲生日，记得准备礼物
   - 周五前提交季度报告

四、实战案例 2：系统健康检查

场景说明

每 4 小时检查一次系统状态，异常时立即通知。

完整配置

javascript

cron(
  action="add",
  job={
    name: "系统健康检查",
    schedule: {
      kind: "cron",
      expr: "0 */4 * * *",  // 每 4 小时
      tz: "Asia/Shanghai"
    },
    payload: {
      kind: "agentTurn",
      message: `
执行系统健康检查：

1. 检查 OpenClaw 网关状态
   - 运行：openclaw gateway status
   - 异常则记录并尝试重启

2. 检查 Nginx 服务
   - 运行：systemctl status nginx
   - 异常则记录并尝试重启

3. 检查磁盘空间
   - 运行：df -h /home
   - 使用率 > 90% 则告警

4. 检查内存使用
   - 运行：free -h
   - 使用率 > 90% 则清理浏览器进程

5. 检查关键进程
   - 运行：ps aux | grep -E "node|nginx"
   - 确认进程正常运行

检查标准：
- 磁盘使用 > 90%：严重
- 内存使用 > 90%：严重  
- 服务未运行：严重

发现严重问题时：
1. 尝试自动修复（如重启服务）
2. 发送通知到飞书
3. 记录详细日志

无问题时回复"系统正常"，不需要发送通知。
      `,
      timeoutSeconds: 600
    },
    sessionTarget: "isolated"
  }
)

告警消息示例

🚨 系统告警 - 2026-03-19 12:00

【严重】磁盘空间不足
- 使用率：92%
- 位置：/home
- 可用：8.5GB

【已执行操作】
1. 清理浏览器缓存：释放 2.1GB
2. 清理日志文件：释放 1.5GB
3. 当前使用率：87%

【建议】
- 考虑清理旧的项目文件
- 检查是否有大文件可删除

五、实战案例 3：网站内容监控

场景说明

每小时检查竞争对手网站，发现新内容时通知。

完整配置

javascript

cron(
  action="add",
  job={
    name: "竞争对手网站监控",
    schedule: {
      kind: "cron",
      expr: "0 * * * *",  // 每小时
      tz: "Asia/Shanghai"
    },
    payload: {
      kind: "agentTurn",
      message: `
监控竞争对手网站更新：

1. 抓取目标页面
   - https://competitor.com/blog
   - https://competitor.com/products

2. 提取最新内容
   - 文章标题
   - 发布时间
   - 摘要内容

3. 与上次检查结果对比
   - 读取 ~/.openclaw/workspace/competitor-last-check.json
   - 比较是否有新内容

4. 如有新内容：
   - 发送通知到飞书
   - 更新检查记录文件
   - 总结新内容要点

5. 如无新内容：
   - 静默退出（不发送通知）
      `,
      timeoutSeconds: 300
    },
    sessionTarget: "isolated"
  }
)

六、Webhook 集成

场景

定时任务完成后，将结果发送到外部系统（如钉钉、企业微信）。

配置示例

javascript

cron(
  action="add",
  job={
    name: "每日数据同步",
    schedule: {
      kind: "cron",
      expr: "0 2 * * *",  // 每天凌晨 2 点
      tz: "Asia/Shanghai"
    },
    payload: {
      kind: "agentTurn",
      message: "执行数据同步任务，完成后返回 JSON 结果",
      timeoutSeconds: 1800
    },
    sessionTarget: "isolated",
    delivery: {
      mode: "webhook",
      to: "https://api.example.com/webhook/sync-result",
      bestEffort: true  // 发送失败不重试
    }
  }
)

Webhook Payload 示例

json

{
  "jobId": "xxx-xxx-xxx",
  "jobName": "每日数据同步",
  "status": "finished",
  "startedAt": 1710813600000,
  "finishedAt": 1710814500000,
  "durationMs": 900000,
  "result": {
    "syncedRecords": 1250,
    "errors": 0,
    "summary": "同步完成，无错误"
  }
}

七、任务管理

查看任务列表

javascript

// 查看所有任务（包括禁用的）
cron(action="list", includeDisabled=true)

更新任务

javascript

// 修改任务执行时间
cron(
  action="update",
  jobId="task-id-xxx",
  patch={
    schedule: {
      kind: "cron",
      expr: "0 9 * * *"  // 改为每天 9:00
    }
  }
)

// 禁用任务
cron(
  action="update",
  jobId="task-id-xxx",
  patch={ enabled: false }
)

// 启用任务
cron(
  action="update",
  jobId="task-id-xxx",
  patch={ enabled: true }
)

删除任务

javascript

cron(action="remove", jobId="task-id-xxx")

手动触发

javascript

// 立即执行一次
cron(action="run", jobId="task-id-xxx", runMode="force")

查看执行历史

javascript

cron(action="runs", jobId="task-id-xxx")

八、最佳实践

1. 任务命名规范

javascript

// ✅ 好的命名
name: "每日早晨报告 - 邮件 + 日历 + 天气"
name: "系统健康检查 - 每 4 小时"
name: "网站备份 - 每天凌晨 3 点"

// ❌ 避免模糊命名
name: "定时任务 1"  // ❌
name: "检查"       // ❌

2. 错误处理

javascript

payload: {
  kind: "agentTurn",
  message: `
执行任务，注意：
1. 任何错误都要记录详细日志
2. 严重错误发送通知
3. 可恢复的错误尝试重试（最多 3 次）
4. 无论成功失败都要更新状态文件
  `,
  timeoutSeconds: 600
}

3. 避免任务堆积

javascript

// 设置合理的超时
timeoutSeconds: 300  // 5 分钟超时

// 检查是否有未完成的任务
const runs = cron(action="runs", jobId="xxx")
if (runs.some(r => r.status === "running")) {
  // 跳过本次执行或终止卡住的任务
}

4. 日志记录

javascript

// 在任务中记录详细日志
message: `
执行数据备份：
1. 记录开始时间和初始状态
2. 每一步都记录进度
3. 记录最终结果和耗时
4. 异常情况记录堆栈信息

日志保存到：/var/log/backup-YYYY-MM-DD.log
`

九、常见问题

Q: 时区如何设置？

A: 使用 tz 字段指定时区，如 "Asia/Shanghai"。不指定则使用 UTC。

Q: 任务执行失败怎么办？

查看执行历史：cron(action="runs", jobId="xxx")
检查错误日志
调整超时时间或重试逻辑

Q: 如何调试定时任务？

A: 使用 cron(action="run", jobId="xxx", runMode="force") 手动触发测试。

Q: 任务可以互相触发吗？

A: 可以，在任务中调用 cron(action="run", jobId="yyy") 触发其他任务。

Q: sessionTarget 选 main 还是 isolated？

isolated：隔离会话，适合独立任务（推荐）
main：主会话，会影响当前对话（慎用）

十、总结

定时任务是实现 AI 助理主动性的关键：

场景	推荐配置
每日报告	cron, 每天固定时间
定期检查	cron, 每 N 小时
定时提醒	at, 一次性执行
间隔任务	every, 相对间隔

合理使用定时任务，让你的 AI 助理从"被动响应"变为"主动服务"！

相关资源：

OpenClaw 定时任务配置完全指南 ​

一、工具概述 ​

cron 工具能力 ​

基本用法 ​

二、调度类型详解 ​

1. Cron 表达式（周期性执行） ​

Cron 表达式格式 ​

特殊字符 ​

2. 间隔执行（相对时间） ​

3. 一次性执行（绝对时间） ​

三、实战案例 1：每日早晨报告 ​

场景说明 ​

完整配置 ​

执行结果示例 ​

四、实战案例 2：系统健康检查 ​

场景说明 ​

完整配置 ​

告警消息示例 ​

五、实战案例 3：网站内容监控 ​

场景说明 ​

完整配置 ​

六、Webhook 集成 ​

场景 ​

配置示例 ​

Webhook Payload 示例 ​

七、任务管理 ​

查看任务列表 ​

更新任务 ​

删除任务 ​

手动触发 ​

查看执行历史 ​

八、最佳实践 ​

1. 任务命名规范 ​

2. 错误处理 ​

3. 避免任务堆积 ​

4. 日志记录 ​

九、常见问题 ​

Q: 时区如何设置？ ​

Q: 任务执行失败怎么办？ ​

Q: 如何调试定时任务？ ​

Q: 任务可以互相触发吗？ ​

Q: sessionTarget 选 main 还是 isolated？ ​

十、总结 ​

OpenClaw 定时任务配置完全指南

一、工具概述

cron 工具能力

基本用法

二、调度类型详解

1. Cron 表达式（周期性执行）

Cron 表达式格式

特殊字符

2. 间隔执行（相对时间）

3. 一次性执行（绝对时间）

三、实战案例 1：每日早晨报告

场景说明

完整配置

执行结果示例

四、实战案例 2：系统健康检查

场景说明

完整配置

告警消息示例

五、实战案例 3：网站内容监控

场景说明

完整配置

六、Webhook 集成

场景

配置示例

Webhook Payload 示例

七、任务管理

查看任务列表

更新任务

删除任务

手动触发

查看执行历史

八、最佳实践

1. 任务命名规范

2. 错误处理

3. 避免任务堆积

4. 日志记录

九、常见问题

Q: 时区如何设置？

Q: 任务执行失败怎么办？

Q: 如何调试定时任务？

Q: 任务可以互相触发吗？

Q: sessionTarget 选 main 还是 isolated？

十、总结